home *** CD-ROM | disk | FTP | other *** search
/ SunSoft Catalyst CDWARE 1996 May to August / Catalyst CDWARE 1996 May to August.iso / .products / .bin / httpd / Solaris_1 / perldoc < prev    next >
Text File  |  1995-06-14  |  4KB  |  176 lines
  1. #!~satyen/bin/perl5/perl
  2.  
  3. #
  4. # Perldoc revision #1 -- look up a piece of documentation in .pod format that
  5. # is embedded in the perl installation tree.
  6. #
  7. # This is not to be confused with Tom Christianson's perlman, which is a
  8. # man replacement, written in perl. This perldoc is strictly for reading
  9. # the perl manuals, though it too is written in perl.
  10. #
  11. # Version 1.01:    Tue May 30 14:47:34 EDT 1995
  12. #        Andy Dougherty  <doughera@lafcol.lafayette.edu>
  13. #   -added pod documentation.
  14. #   -added PATH searching.
  15. #   -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
  16. #    and friends.
  17.  
  18. =head1 NAME
  19.  
  20. perldoc - Look up Perl documentation in pod format.
  21.  
  22. =head1 SYNOPSIS
  23.  
  24. B<perldoc> [B<-h>] PageName|ModuleName
  25.  
  26. =head1 DESCRIPTION
  27.  
  28. I<perldoc> looks up a piece of documentation in .pod format that is
  29. embedded in the perl installation tree or in a perl script, and displays
  30. it via pod2man | nroff -man | $PAGER.  This is primarily used for the
  31. documentation for the perl library modules. 
  32.  
  33. Your system may also have man pages installed for those modules, in
  34. which case you can probably just use the man(1) command.
  35.  
  36. =head1 OPTIONS
  37.  
  38. =over 5
  39.  
  40. =item B<-h> help
  41.  
  42. Prints out a brief help message.
  43.  
  44. =item B<PageName|ModuleName>
  45.  
  46. The item you want to look up.  Nested modules (such as C<File::Basename>)
  47. are specified either as C<File::Basename> or C<File/Basename>.  You
  48. may also give a descriptive name of a page, such as C<perlfunc>.
  49.  
  50. =back
  51.  
  52. =head1 ENVIRONMENT
  53.  
  54. Any switches in the C<PERLDOC> environment variable will be used before the 
  55. command line arguments.  C<perldoc> also searches directories
  56. specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
  57. defined) and C<PATH> environment variables.
  58. (The latter is so that embedded pods for executables, such as
  59. C<perldoc> itself, are available.)
  60.  
  61. =head1 AUTHOR
  62.  
  63. Kenneth Albanowski <kjahds@kjahds.com>
  64.  
  65. Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
  66.  
  67. =head1 SEE ALSO
  68.  
  69. =head1 DIAGNOSTICS
  70.  
  71. =cut
  72.  
  73. if(@ARGV<1) {
  74.     die <<EOF;
  75. Usage: $0 [-h] PageName|ModuleName
  76.  
  77. We suggest you use C<perldoc perldoc> to get aquainted 
  78. with the system.
  79. EOF
  80. }
  81.  
  82. use Getopt::Std;
  83.  
  84. sub usage{
  85.         warn "@_\n" if @_;
  86.     die <<EOF;
  87. perlman [-h] PageName|ModuleName...
  88.     -h   Display this help message.
  89. PageName|ModuleName...
  90.          is the name of a piece of documentation that you want to look at. You 
  91.          may either give a descriptive name of the page (as in the case of
  92.          `perlfunc') or the name of a module, either like `Term::Info', 
  93.          `Term/Info'.
  94.          
  95. Any switches in the PERLDOC environment variable will be used before the 
  96. command line arguments.
  97.  
  98. EOF
  99. }
  100.  
  101. use Text::ParseWords;
  102.  
  103. unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
  104.  
  105. getopts("h") || usage;
  106.  
  107. usage if $opt_h;
  108.  
  109. $index = $opt_i;
  110. @pages = @ARGV;
  111.  
  112. sub containspod {
  113.     my($file) = @_;
  114.     local($_);
  115.     open(TEST,"<$file");
  116.     while(<TEST>) {
  117.         if(/^=head/) {
  118.             close(TEST);
  119.             return 1;
  120.         }
  121.     }
  122.     close(TEST);
  123.     return 0;
  124. }
  125.  
  126. sub searchfor {
  127.     my($s,@dirs) = @_;
  128.     $s =~ s!::!/!g;
  129.     printf STDERR "looking for $s in @dirs\n";
  130.     
  131.     foreach $dir (@dirs) {
  132.         if( -f "$dir/$s.pod") { return "$dir/$s.pod" }
  133.         elsif( -f "$dir/$s.pm" and containspod("$dir/$s.pm"))
  134.             { return "$dir/$s.pm" }
  135.         elsif( -f "$dir/$s" and containspod("$dir/$s"))
  136.             { return "$dir/$s" } 
  137.         elsif( -f "$dir/pod/$s.pod") { return "$dir/pod/$s.pod" }
  138.         elsif( -f "$dir/pod/$s" and containspod("$dir/pod/$s"))
  139.             { return "$dir/pod/$s" } 
  140.     }
  141.     return ();
  142. }
  143.  
  144.  
  145. $ENV{PAGER} ||= "more";
  146.  
  147. foreach (@pages) {
  148.     print STDERR "Searching for $_\n";
  149.     # We must look both in @INC for library modules and in PATH
  150.     # for executables, like h2xs or perldoc itself.
  151.     @searchdirs = @INC;
  152.     push(@searchdirs, split(':', $ENV{'PATH'}) );
  153.     @files= searchfor($_,@searchdirs);
  154.     if( @files ) {
  155.         print STDERR "Found as @files\n";
  156.     } else {
  157.         print STDERR "No documentation found for $_\n";
  158.     }
  159.     push(@found,@files);
  160. }
  161.  
  162. $cmd=$filter="";
  163.  
  164. if( ! -t STDOUT ) { $opt_f = 1 }
  165.  
  166. $cmd = "pod2man - | nroff -man";
  167. if( ! $opt_f ) { $filter = "|$ENV{PAGER}" };
  168.  
  169. open(OUT,"|$cmd$filter");
  170. foreach (@found) {
  171.     open(IN,"<$_");
  172.     print OUT while <IN>;
  173.     close(IN);
  174. }
  175. close(OUT);
  176.